Bug Proofing Visual Basic: A Guide to Error Handling and Prevention
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471323519
Publication Date: 11/01/98

Use Lots of Comments

It is hard to use too many comments. Your code may not be as exciting if you explain every little detail, but the idea is to inform, not to entertain. Any comment that increases understanding is a good comment.

In one project I worked on, we followed a rigorous commenting strategy. The program contained a normal number of comments throughout the code. Then far to the right beyond the 80th column, we placed additional comments that explained every single line in excruciating detail. We were all working on 80-column monitors, so you only saw those comments if you wanted to. Most of the time the normal comments were enough, but if you got confused, you could switch to 132-column display to see the extra comments.

When the project was finished, we transferred the program to the company’s maintenance organization. Even though you never saw these comments unless you looked for them, the maintenance group decided they were too distracting so they removed them. Their philosophy was, “Use comments only when necessary.”

About a month later, they removed a major subsystem from the program and replaced it with a less-functional version they purchased from a third-party vendor. They did this because they could not understand the subsystem we built. The reason they could not understand it was that they had removed all of the comments.

Do not adopt the, “Use comments only when necessary,” strategy. Instead, use comments wherever they can help clarify the code.

Self-Test

You might think it makes little sense to include an example of bad comments here. Unfortunately, it is just as easy to write bad comments as it is to write bad code. In fact, because bad comments do not cause syntax errors or faulty behavior, they are easier to write and ignore. Their effects are felt only indirectly through increased bug counts and debugging time.

The comments in the following code violate several of the guidelines described in this chapter. Appendix A, “Self-Test Solutions,” contains an improved version of this code.

Option Explicit

‘ True when the user is drawing.
Private Drawing As Boolean

‘ Save mouse position.

Private LastX As Single
Private LastY As Single

‘ ************************************************
‘ Purpose: Start drawing.
‘
‘ Method:  Use the X and Y coordinates to see where
‘          the mouse currently is.
‘ ************************************************
Private Sub picDrawingArea_MouseDown(Button As Integer, _
        Shift As Integer, X As Single, Y As Single)

 ‘ Set Drawing to true.
    Drawing = True

 ‘ Record this point's location.

    LastX = X
    LastY = Y
End Sub

‘ ************************************************
‘ Purpose: Process the user's mouse move event in
‘          the drawing area.
‘
‘ Method:  Use the X and Y coordinates to see where
‘          the mouse currently is.
‘
‘ Errors:
‘    If the user draws outside the drawing area,
‘    raise error OUT_OF_BOUNDS.
‘ ************************************************
Private Sub picDrawingArea_MouseMove(Button As Integer, _
        Shift As Integer, X As Single, Y As Single)

 ‘ If we are not drawing, BAIL OUT.
    If Not Drawing Then Exit Sub

    If X < 0 Or _
       Y < 0 Or _
       X > picDrawingArea.ScaleWidth Or _
       Y > picDrawingArea.ScaleHeight _
    Then      ‘ Make sure we are in the drawing area

        Err.Raise OUT_OF_BOUNDS, _
            “picDrawingArea”, _
            “Cannot draw outside the drawing area.”
    End If

 ‘ Draw a line from (LastX, LastY) to (X, Y).
    picDrawingArea.Line (LastX, LastY)-(X, Y)

 ‘ Save X and Y.

    LastX = X
    LastY = Y
End Sub

‘ ************************************************
‘ Purpose: Finish drawing.
‘
‘ Method:  Set Drawing to False.
‘ ************************************************
Private Sub picDrawingArea_MouseUp(Button As Integer, _
        Shift As Integer, X As Single, Y As Single)

    Drawing = False

End Sub

Summary

Good comments give the reader extra information that makes the code more understandable. By making it easier for readers to understand the code, comments reduce the chances of bugs being introduced into the program. Do not underestimate the power of good comments for preventing bugs.

Table 7.1 summarizes the types of information a header-style comment for a file should contain. Table 7.2 lists information that a routine’s header-style comment should include.